Change packages

This topic describes how to enable and to use change packages.

In this topic:

Enable change packages

Change packages is an AccuRev feature that associates changes made to an element with a specific issue in an issue tracking system; users are required to specify that issue number each time they promote changes out of a workspace. To enable change packages for your Git commits you need to do the following:

• In AccuRev, ensure that change packages are configured on the relevant AccuRev Server. See the AccuRev on-line Help, which includes all the current AccuRev documentation. Use the index and search mechanisms in the on-line Help to learn how to configure change packages, and optionally, third-party issue tracking systems (ITS) if you are using something other than kandoMaintain.
• In GitCentric, specify the ITS you are using and the format of the Git commit message you will require users to follow when pushing commits. You specify this information on the AccuRev Connector panel of the Repositories page as described in this section.

Once you have enable change packages, you must inform your users of the requirement to add comments to their commits in the format you choose. The process for using a regular expression to specify the commit message format is described in the following section.

Back to top

Specifying the Commit Message Format

This section describes how to specify the commit message format.

To specify the commit message format that users will be required to follow when pushing commits (and from which the GitCentric bridge will obtain the issue number required to enforce AccuRev change packages):

To specify the commit message format:

1. Click the Administration button and then click the Repositories menu.
2. Click the repository for which you want to enable change packages.
3. On the Repositories page, click AccuRev Connector menu and locate the Associate Issues With Commits section. (For more information, see AccuRev Connector page).

   

4. In the Issue Tracking System field, specify whether you are using kandoMaintain or a third-party issue tracking system.

   Tip: If this field is disabled, specify the AccuRev Server connection information and click the Save button.

5. In the Regular Expression field, use a regular expression to specify the format of the commit message you require, Resolves issue 1234, for example. You can accomplish this by either:
   • Entering a regular expression. GitCentric displays sample expressions as soon as you begin typing in the field, as shown in the following illustration.

     

   • Clicking the Test... button to display a dialog box that lets you experiment and verify that the regular expression you enter satisfies your requirements.

     

     Refer to the instructions on the dialog box for its use.

     Clicking the Save button on this dialog box saves your regular expression to the Regular Expression field in the Associate Issues With Commit section of the AccuRev Connector panel.

6. Click the Save button in the Associate Issues With Commit section to save your work.

   See GitCentric Regular Expressions for information on regular expressions and their use in GitCentric.

Back to top

GitCentric Regular Expressions

One of the strengths of AccuRev is to associate all of the files affected by a particular change to an issue number tracking that change. This grouping of affected files is called a change package. (See the AccuRev documentation for information about change packages.) If you have change packages enabled on your AccuRev Server, either through kandoMaintain or through a third-party issue tracking system, you may need to enforce the practice of including the issue number in the comment related to Git commits. That is the purpose of the Regular Expression field: to specify a commit message format that users must follow when pushing a change in Git that will be synchronized to AccuRev. The default example provided in the UI (Resolves\s+([\d,]+):) forces users to start their commit messages with Resolves <issue number>:.

If this is not found, the push will be rejected.

A discussion of Java regular expressions is beyond the scope of this document, but here are examples of what comments would be valid for some of these predefined expressions:

(?:Resolves|Resolved|Fixes|Fixed)\s*((?:(?:US|DE)[\d, ]*)*)

This format would be useful for the Rally issue tracking system, which makes use of user stories (US) and defects (DE): The comments can start with Resolves, Resolved, Fixes, or Fixed, followed by white space, and then any number of issue numbers prefixed with US or DE:

Resolves US302, DE1405, US27
Fixed DE12849

Resolved\s+([\d,]+)

This format would be adequate for simple environments where the comment always starts with Resolved, followed by white space, followed by any number of issues, separated by commas:

Resolved 12576
Resolved 34, 149, 11057, 686

Use a search engine and search for Java regular expressions for more information about these formats.

Back to top

Troubleshooting change package errors

This section contains troubleshooting techniques for change packages.

Your users may see change package error messages upon a push, and they must contact you as the GitCentric administrator for assistance in rectifying them. Errors are generated when GitCentric synchronizes the push with the AccuRev Server, and the AccuRev Server encounters a problem with the elements that comprise the change package. You (the GitCentric administrator) must act as a liaison to the AccuRev side of the world, including understanding change package errors and helping your end-users correct them. The following table summarizes some errors you might encounter and what you can do to address them.

Issue	Problem	Solution
Change Package Required	An issue must be included in the commit comments, in the format dictated by the regular expression that was specified when change packages were enabled.	Use git commit --amend to effectively rewrite the commit message.
Issue did not meet criteria	Typically means that the commit comment was present and generally formatted correctly, but the state of the kandoMaintain issue was incorrect (for example, Completed instead of WIP).	Use git commit --amend to effectively rewrite the commit message.
cpk merge required	Results during parallel development when two users make changes on the same file related to the same issue and one user tries to push his or her changes before pulling the other’s, creating the merge requirement.	To address an existing error, you will need to create a new issue and push changes against it. To avoid such problems in the future, instead of using a simple git pull, use git pull --rebase to provide serialized commits, avoiding the need to separately merge remote changes in your branch.

For understanding and correcting change package errors that are caused beyond the GitCentric regular expression filter, search the online help.

Back to top